GROD Tutorial

Introduction, why find river obstructions?

      River obstructions in the form of dams, locks, and other such barriers, are a globally important impact that humans have had on the movement of water, sediment, organisms, and nutrients from ocean to sea. Despite existing datasets of the worlds largest dams like GRanD, there is not a global inventory of obstructions to rivers. That is the goal of this project: Identify and categorize human-built river barriers for rivers wider than 30 meters across the globe. These barriers can vary enormously in their size, volume of water disrupted, and biological permeability (can fish swim past them?). We will try to capture some of this broad variation in river obstructions, so we need to be clear about the different barriers that may cross a river, which are listed here in order from most impermeable to most permeable.

      We will be using google earth engine for this project and instructions on how to use this software are detailed below. We will also be using the Global River Widths from Landsat dataset generated by George Allen and Tamlin Pavelsky. This dataset highlights all rivers wider than 30m, and shows up as a yellow line in the images below.

Barrier types

Here is a decision tree to help you differentiate between different types of river obstructions. Detailed descriptions of each obstruction type are listed in the next section.

Dams

Dams should be the most obvious barriers you will encounter. These cover the entire river channel, not allowing any water to pass through except through the dam structure itself. These are strong barriers to both the flow of water and the movement of organisms above and below the dam. Examples below.

Dam Example 1

Dam Example 2

Locks

Locks are a subset of dams and are structures placed on rivers to help barges and other river traffic move up and downstream, these can look a lot like dams, and typically fully obstruct the flow of water in the river, however the lock system itself can be permeable to fish who can swim into the lock area and make their way upstream, though this is still a significant barrier it is not impossible to imagine fish moving upstream. Only full dams (concrete complete channel obstruction) with lock passages should be classified as locks.

Lock Example

Channel dams

Channel dams fully obstruct at least one but not all the channels of a braided river. These can have significant upstream hydrologic impacts, but are less likely to alter ecological processes in the larger river section. Any type of dam (permeable, partial or otherwise) that is on a channel, should be classified as a channel dam.

Channel Dam Example 1

Channel Dam Example 2

Partial Dams

Partial dams > 50%

Throughout your search for dams, you will likely encounter some dams that do not cover 100% of the river channel. For now we are just keeping track of these dams in two broad categories. Dams that cover > 50% of the channel, and dams that cover < 50% of the chanel but more than 10%. These partial dams can be broken on the side of the channel or in the center but should be recorded as partial dams.

Partial Dam Example 1

Partial Dam Example 2

Partial dams < 50%

This barrier covers about 30% of the channel and should be included in the database.

Partial Dam Example 3

Partial dams < 10% – Ignore these

Little jetties or piers or tiny barrages will not be included in the dataset.

Partial Dam Example 4

Low/Permeable dams

Many dams will be “low-head” or have a small height difference upstream and downstream of the dam. These dams can look a lot like natural riffle or natural waterfalls and should only be included in the dataset if you are very sure that the structure is indeed a manmade river barrier. These will likely only be identifiable in parts of the world with higher resolution imagery. In earlier iterations of this project we called these permeable dams, but that name is misleading as one can not be sure if a dam is permeable without more focused local study. For now we have kept the permeable name in the category to keep nomenclature the same between different users, but for future work and publication these will more simply be called low-head dams.

Low Dam 1

Low Dam 1 Google Street Bridge View

Low Dam 2

Low Dam 3

Low Dam 4 with lock feature

Low Dam 5

Uncertain

Many times in your search you will come across structures that could either be dams or natural riffles or just a random rock slide. To be cautious in our assignments you should label these in a broad category of uncertain.

Uncertain Dam 1

Uncertain Dam 2

Natural riffles

We don’t have to record these natural features, but the category is available to you if you find it interesting or want to start a project about natural riffles.

Riffle 1

Riffle 2

Set up

1. Sign up for Google Earth Engine: https://earthengine.google.com/

2. Send Xiao an email: yangxiao@live.unc.edu
   1. He will add you to our slack channel and will share all the data you need to get started (You need Permissions to use GRWL)
3. Send Wayana an email: whyana@live.unc.edu
   1. She will add you to the Fusion Table (which is where you will be recording your progress)
4. Set up a shareable Google Drive Folder
   1. Using your Google account (the same one you made your Google Earth Engine account with), open up your Google drive (https://drive.google.com/drive/my-drive) and make a new folder in your drive to store data from the project. Please include your name in the name of the folder, ex. ‘BobJoeDamData’
   2. Once the folder is created, please share it with the group. To do this, you can right click on the folder and click ‘share.’ Next, click ‘get shareable link’ in the top right corner, and set link sharing to ‘Anyone with the link can edit.’ Lastly, click ‘copy link,’ and paste the link in this Google Sheets document alongside your name.
      1. https://docs.google.com/spreadsheets/d/1V0gvGqpq4IyfzihJSJgdDur_GBUynXaQ2hC8YrgKIuc/edit?usp=sharing

Using Google Earth Engine

Getting started with GROD in Google Earth Engine

1. Go to the project Github page at https://github.com/GlobalHydrologyLab/GROD/blob/master/1_user_interface_script/GROD.js. Copy and paste everything into a blank Google Earth Engine editor (https://code.earthengine.google.com/).

2. To generate all of the dam categories, you will need to convert them to import records. You can do this by hovering over the first few lines of code var Dams =... and earth engine will prompt you to import these records. Click convert to do so.

3. Write your name at the top of the script, and hit the ‘Save’ button. This will save a copy of the script to your script repository. Please take note the name of the file just saved as you will need this to go back and continue your work.

4. You will be looking for obstructions one grid cell at a time. To begin from grid cell 0, hit ‘Next cell.’ If you are starting with grid cell other than 0, enter the grid cell number at the bottom of the screen and hit enter on your keyboard.

The full workflow

1. Go to https://code.earthengine.google.com/

2. Go to the ‘Scripts’ tab in the top left corner of your screen. Click on the script.

3. Hit ‘Run’ at the center top of your screen.

4. At the bottom of your screen, enter the number of the cell that you last worked on, and hit enter on your keyboard. To pick a new cell to work on, refer to the cell tracking sheet. Fill in your name under the ‘name’ column to let others know you have started on it. When you finish the cell, fill in the ‘date’ column in mm/dd/yy format.

Finding and identifying obstructions

1. You will need to follow the yellow GRWL river lines upstream until you find an obstruction. Like here:

2. When you find a dam, a road, or some other obstruction you will need to click on the top left geometry bar and select the point geometry icon (shown in green).

3. After you have selected the point type you will need to choose the obstruction type.

4. Continue to scroll around your grid cell until you have finished identifying all of the obstructions in your area.

5. When you have finished your cell, fill in the ‘date’ column here: cell tracking sheet

6. Hit next at the bottom of your screen to go to the next grid cell.

Editing

1. If you have made a mistake, click on the hand icon at the top left-hand corner of the map (see the red circle on the figure below). Next, click on the point you dislike. Lastly, hit backspace or delete on your keyboard.

2. To resume adding points, go back to the geometry bar (see the yellow box on the figure below), and click on the type of obstruction you want to add.

Finishing up each day

When you are done each day, please do the following:

1. Hit ‘Run’ at the top center of your screen or Ctrl + Enter on your keyboard.

2. Next, go to the ‘Task’ panel at the top right portion of your screen. You should see an item called ‘export_data.’

3. Hit ‘Run’ next to the ‘export_data’ item.

4. A window will pop up. Please fill it out as follows:
   1. Task name. Your name and the date in the following format: Jones_YYYYMMDD
   2. Drive folder. Whatever you named your folder in Google Drive.
   3. Filename: Same as the task name.
   4. Format. ‘CSV’

5. Hit ‘Run.’

6. Make sure to record all the cells you worked on today, the current date, and your name on in the cell tracking sheet

NOTE: After you enter your information for a grid cell and refresh the Fusion table, you may need to hit the little arrow next to the grid cell column that will appear next to the column header when you put your mouse over it. This will resort the column, and your info should reappear.

7. Hit ‘save’ at the top of the page to save your work. You’re done!

Validation ((This should probably be changed once Ted updates validation script))

1. When you start out we will be assessing your accuracy by having you identify river obstructions in parts of the world where we have good obstruction databases. These datasets exist in the Southeastern USA and in France.

2. Before you do an independent grid cell, you will need to do a validation cell which is either 389 (France) or 156 (USA).

3. When you have finished these grid cells, let us know and we will make sure that you are identifying the majority of the obstructions in the validation datasets.

Miscelaneous skills

Identifying a grid cell based on location

You may want to know what a gridcell number is at a given location. To do this:

1. Click on the inspector tab at the top right of the screen.

2. Click on a location on the map. From there, you will see information pop up in the inspector window. Click on “GRID:” -> “Feature…” -> “Properties.” The grid id is labeled as “fxd_ndx.” You can then input this number at the bottom of your screen and hit enter to go to the corresponding gridcell on the map.

How to upgrade your script

The latest version of the Google Earth Engine script will be posted on the project github page at (https://github.com/GlobalHydrologyLab/GROD) and we will update the content of this tutorial to reflect the changes we made to our script. If you’re working with a older version of the script, we recommend you to upgrade your version of script with the following three steps:

1. Backup your current working file. To do this, click the little triangle symbol next to the “save” button, choose “save as”, then save a backup script with a name of your preference.
2. Copy and paste the latest script from the project github page. First point your browser to (https://github.com/GlobalHydrologyLab/GROD/blob/master/1_user_interface_script/GROD.js). Copy all the lines starting from the “// Import related datasets”, and replace all the lines starting from the “// Import related datasets” in your own saved working script. Warning: Never replace the category definitions at the beginning of your working script as they contain all the data you’ve collected!!!
3. After upgrading your script, you should be able to continue your work and your previously collected data should be there on the map. If not, please contact us immediately.

Useful keyboard shortcuts

High Priority Grid Cells

Because of ongoing work in the lab, the USA is a priority and you can use grid cell 118 as a reference point (roughly the middle of the USA) to find appropriate grid cells within the country.